$env:AZURE_DEVOPS_EXT_PAT = bjlhfo7evyvre5rsxhyhxy6…..tv6hklzrrl3ydwfan2k7d5awq"

Voreinstellungen

Wer mit mehreren Organisationen und Projekten arbeitet, wird beim Azure DevOps CLI immer wieder bei den einzelnen Befehlen die Organisation und den Projektnamen festlegen müssen:

az pipelines list --organization https://dev.azure.com/ITVDemo --project "MiracleList"

Dabei ist man bei –organization gezwungen, den ganze URL anzugeben. Eine Abkürzung der Parameternamen ist möglich, soweit noch eindeutig:

az pipelines list --org https://dev.azure.com/ITVDemo --p "MiracleList"

Man kann aber die Organisation nicht mit –o abkürzen, da es auch noch den Parameter –output gibt. Die ständige Wiederholung dieser allgemeinen Parameter kann man durch eine zentrale Vorgabe vermeiden:

az devops configure --organization https://dev.azure.com/ITVDemo --project "MiracleList"

Dadurch kann man im Folgenden verkürzt schreiben: az pipelines list

SIE LIEBEN AZURE?

Entdecken Sie die BASTA! Tracks

Mehr erfahren

Ausgabeformate zur Wahl

Azure DevOps CLI liefert im Standard alle Ausgaben im JSON-Format. Dies ist zwar für Maschinen gut weiterzuverarbeiten, doch für Menschen nicht gut lesbar. Insgesamt stehen zur Verfügung:

• json (einfarbige JSON-Ausgabe)
• jsonc (mehrfarbige JSON-Ausgabe)
• none (keine Ausgabe)
• table (ASCII-Tabelle)
• tsv (tabulatorgetrennt)
• yaml (YAML)

Das Ausgabeformat kann man bei jedem einzelnen Azure-CLI-Befehl mit dem Parameter –output, abgekürzt mit -o,festlegen. Wie Abbildung 3 zeigt, beschränkt sich die Tabellenausgabe auf die wesentlichen Spalten.

Das Standardausgabeformat kann der Benutzer persistent in der Datei C:\Users\BenutzerName\.azure\config ändern (Listing 1). Diese Datei kann er auch interaktiv mit dem Befehl az configure bearbeiten.

[cloud]
name = AzureCloud
[core]
first_run = yes
output = table
collect_telemetry = no
cache_ttl = 10
[logging]
enable_log_file = no

Weiterverarbeitung der Ergebnisse

Als eingefleischter Liebhaber der objektorientierten Programmierung und des objektorientierten Pipelinings mit Objekten in der PowerShell fehlt dem Autor dieses Beitrags in der Liste der Ausgabeformate natürlich object. Man muss sich die Frage stellen, warum Microsoft zur Implementierung Python verwendet hat. C# oder Visual Basic .NET gibt es ja nun seit einiger Zeit auch plattformneutral, und diese Sprachen hätten den Vorteil gehabt, dass sie auch direkt .NET-Objekte für die PowerShell produzieren könnten. Wie so oft erleben wir auch hier, dass bei Microsoft leider viele technische Entscheidungen eher willkürlich in einzelnen Fachbereichen statt zentral und strategisch getroffen werden.
Die Azure DevOps-CLI-Befehle in der PowerShell auszuführen, lohnt sich dennoch, denn die PowerShell kann leicht JSON in .NET-Objekte verwandeln; dafür gibt es seit Windows PowerShell 3.0 das eingebaute Commandlet ConvertFrom-Json. Dieses Commandlet wandelt eine Zeichenkette im JSON-Format in .NET-Objekte um. Intuitiv würde man als PowerShell-Benutzer dann schreiben:

az pipelines list -o JSON | convertfrom-JSON | where-object { $_.name -notlike "*Backend*" } | sort-object name | format-table name, url

Allerdings wundert man sich, dass zwar die Tabellenausgabe mit den beiden gewünschten Spalten vorhanden ist, aber weder der Filter mit dem Commandlet where-object noch die Sortierung mit sort-object wirkt. Das liegt am Commandlet ConvertFrom-Json, bei dem das PowerShell-Entwicklerteam bei der Implementierung etwas verbockt hat. Wenn sich an der Wurzel der JSON-Datei ein Array befindet, legt das Commandlet das Array in die Pipeline. Üblicherweise entpacken aber Commandlets ein Array in Einzelobjekte. Microsoft hat das Problem leider bis heute nicht behoben>/a>. Die Umgehung dieses Problems ist, entweder Foreach-Object explizit in die Pipeline zu setzen:

az pipelines list -o JSON | convertfrom-JSON | foreach-object { $_} | where-object { $_.name -notlike "*Backend*" } | sort-object name | format-table name, url

oder den vorderen Teil zu klammern:

(az pipelines list -o JSON | convertfrom-JSON) | where-object { $_.name -notlike "*Backend*" } | sort-object name| format-table name, url

Work Items behandeln

Einige der Azure-DevOps-CLI-Befehle haben bereits eingebaute Filter, so kann man beispielsweise Work Items mit der SQL-ähnlichen Work Item Query Language (WIQL) aussortieren:

az boards query --wiql "SELECT System.ID, System.Title, System.WorkItemType, System.AreaPath, System.AssignedTo, System.State from workitems order by System.ID asc"

Mit PowerShell-Variablen kann man diesen Befehl natürlich auch in mehrere Zeilen aufteilen:

$wiql = "SELECT System.ID, System.Title, System.WorkItemType, System.AreaPath, System.AssignedTo, System.State from workitems order by System.ID asc"
az boards query --wiql $wiql

Ebenso ist es möglich, WIQL-Filter und das Filtern mit Where-Object in der PowerShell zu kombinieren. Der folgende Befehl filtert erst alle an einen Benutzer zugewiesenen Work Items, die nicht erledigt sind. Dann erfolgt in der PowerShell Pipeline ein weiterer Filter auf das Wort „Angular“ im Titel:

$wiql = "SELECT System.ID, System.Title, System.AssignedTo, System.State from workitems WHERE [System.AssignedTo] = '[email protected]' and state <> 'Done' order by System.ID asc"
(az boards query --wiql $wiql -o json | convertfrom-JSON).fields | where-object { $_."System.Title" -like "*Angular*" } | format-table "System.ID", "System.Title"

Der explizite Zugriff .fields ist hier notwendig, da die JSON-Struktur, die das Azure CLI liefert, etwas komplexer ist. An der Wurzel ist ein Array von Objekten. Die Objekte enthalten die Eigenschaften des Work Items aber nicht direkt, sondern ein Unterobjekt “fields” (Listing 2).

[
  {
    "fields": {
      "System.AssignedTo": {
        "_links": {
          "avatar": {
            "href": "https://nlhsdemo.visualstudio.com/_apis/GraphProfile/MemberAvatars/msa.N2NlNTFmMWYtODBhYy03MzVlLThmOWEtY2FhNzgyNjAzNGQz"
          }
        },
        "descriptor": "msa.N2NlNTFmMWYtODBhYy03MzVlLThmOWEtY2FhNzgyNjAzNGQz",
        "displayName": "Dr. Holger Schwichtenberg",
        "id": "0a31ed99-da1e-4412-913b-5da20050c88f",
        "imageUrl": "https://nlhsdemo.visualstudio.com/_apis/GraphProfile/MemberAvatars/msa.N2NlNTFmMWYtODBhYy03MzVlLThmOWEtY2FhNzgyNjAzNGQz",
        "uniqueName": "[email protected]",
        "url": "https://spsprodcus1.vssps.visualstudio.com/A7fbad96a-dc90-4656-af24-f37c38c5694b/_apis/Identities/0a31ed99-da1e-4412-913b-5da20050c88f"
      },
      "System.Id": 18,
      "System.State": "New",
      "System.Title": "Sicherheit verbessern: Secrets, z.B. im ConnectStrings, müssen verschlüsselt gespeichert werden"
    },
    "id": 18,
    "relations": null,
    "rev": 5,
    "url": "https://itvdemo.visualstudio.com/_apis/wit/workItems/18"
  },
…
]

Außerdem ist bei dem PowerShell-Befehl zu beachten, dass die WorkItem-Eigenschaftennamen in Anführungszeichen stehen müssen, falls sie Punkte enthalten (wie z. B. bei System.State und Microsoft.VSTS.Common.Severity). Den Punkt interpretiert die PowerShell genauso wie andere objektorientierte Sprachen als Trennzeichen zwischen Objekt und Eigenschaft. Hier Punkte im Namen zu verwenden, war nicht sehr weise von Microsoft.
Die Namen der Work-Item-Eigenschaften für die Prozesse Scrum und Agile findet man auf dem Azure-DevOps-Spickzettel, der dieser Ausgabe beiliegt. Vielfach findet man hier noch VSTS im Namen; hier wird Microsoft den alten Namen nicht loswerden, außer man riskiert Breaking Changes oder implementiert Aliase.

Praxisbeispiele

Zum Abschluss noch einige schöne Praxisbeispiele zum Einsatz des Azure DevOps CLI. Das erste Beispiel zeigt das Anlegen eines Work Items mit mehreren Eigenschaften (Listing 3). Von az boards work-item create wird eine JSON-Ausgabe angefordert, die mit Hilfe der PowerShell ausgewertet wird. Hier ist eine Klammer um ConvertFrom-Json nicht notwendig, denn der Azure-DevOps-CLI-Befehl liefert nur ein einzelnes Objekt, keine Menge. In dem Befehl fällt zudem auf, dass man einige wenige Eigenschaften direkt setzen kann über Parameter des CLI-Befehls; die meisten Eigenschaften kann man jedoch nur über den generischen Parameter –fields setzen. Auf –fields folgt eine Liste von durch ein Gleichheitszeichen getrennten Name-Wert-Paaren:

$wi = (az boards work-item create --type Bug --title "Absturz bei der Eingabe von 0 im Feld Preis" --description "Die Spalte Preis erlaubt nicht die Zahl 0!" --discussion "Das hatte ich in der letzten Version schon festgestellt!" --field "Microsoft.VSTS.TCM.ReproSteps=

” “Microsoft.VSTS.Common.AcceptanceCriteria=

” “Microsoft.VSTS.TCM.SystemInfo=Windows 10 v1903” –assigned-to “[email protected]” -o json)
$workItemID = ($wi | ConvertFrom-Json).ID

Das zweite Beispiel zeigt die Änderung eines Work Items:

az boards work-item update --id 30 --field "Microsoft.VSTS.TCM.SystemInfo=Windows 10 v1903" "Microsoft.VSTS.Common.Priority=1" "Microsoft.VSTS.Common.Severity=2 - High"

Das dritte Beispiel zeigt die Zuordnung zwischen zwei Work Items:

az boards work-item relation add --id 21 --target-id 24 --relation-type "Tests"

Eine Liste aller möglichen Zuordnungstypen in einem Projekt erhält man mit:

az boards work-item relation list-type

Zum Schluss noch das Starten einer Build Pipeline:

az pipelines build queue --definition-name MiracleListAngularClientBuild

Weitere sinnvolle Anwendungen des Azure DevOps CLI finden Sie auf dem dieser Ausgabe des Windows Developer beiliegenden Spickzettel.